JavaScript Antipatterns — Naming and Documentation

JavaScript lets us do a lot of things. It’s sometimes too forgiving in its syntax.

In this article, we’ll look at some antipatterns that we should avoid when we format JavaScript code, including naming and documentation.

Naming Conventions

JavaScript code has some naming conventions that are standard to it.

We should follow it so that we can have consistency within a project.

However, we can tweak them slightly to fit our own style as long as it doesn’t conflict with other people’s styles.

Capitalizing Constructors and Classes

Constructors are names PascalCase.

Each word has the first letter capitalized.

For instance, we can define one as follows:

function FooConstructor() {...}

or:

class MyClass {...}

Other functions are camelCase.

Separating Words

Most identifiers are usually written in camelCase except for constructors as we mentioned above.

For instance, we can define variables by writing let firstName; .

A function can be written as calculateArea() .

Constants are written in all upper case with words separated by an underscore.

For instance, we can write const MAX_DONUTS = 1;

Property names are also usually written in camelCase, so we get person.firstName = 'bob';

Other Naming Patterns

There’re some names that don’t follow those conventions.

For instance, there are constant properties in the Number object that are written in the upper case.

For instance, Number.MAX_SAFE_INTEGER is a constant that has an upper case property name.

That indicates that it’s constant.

We may also have properties beginning with an underscore to indicate that it’s private.

Since there are no private variables in constructors and classes, we may have to do that to indicate that we shouldn’t access it directly.

For instance, we may write:

class Person {
  constructor(name) {
    this._name = name;
  }
}

We can do the same with methods. For instance, we can write:

class Person {
  constructor(name) {
    this._name = name;
  }

  _greet() {
    //...
  }
}

Likewise, we can do the same with objects:

const person = {
  getName() {
    return `${this._getFirst()} ${this._getLast()}`;
  },
  _getFirst() {
    // ...
  },
  _getLast() {
    // ...
  }
};

_getFirst and _getLast are private as indicate by the underscore at the beginning of the name.

So we shouldn’t call them directly even though we can.

Alternatively, we can use the following conventions for private and protected members:

• trailing underscore means private
• leading underscore for protected and 2 for private

We can adapt this to our liking.

Writing Comments

We should write comments for code that isn’t immediately obvious.

That means we should write comments on every variable or statement.

We should just explain things that aren’t clear in the code.

Also, we can discuss any decisions that we made if we need to justify them.

Writing API Docs

API docs are essential. If we let external users use our API then we need to document them.

Even though it might be boring and unrewarding, we got to do it so that everyone knows how to use our APIs.

We can usually write some comments and convert them into API documentation by using things like JSDoc.

Writing to Be Read

We got to write our docs so that it’s actually useful to the readers who read it.

Otherwise, we’re wasting our time. And the readers of our documentation would be frustrated.

The information should be accurate and the structure got to be clear and easy to follow.

We probably have to go through multiple drafts to get them right.

Writing API docs also provides an opportunity to revisit our code, so we can take a look at the code and revision it at that time if needed.

We should assume that other people would read it. Otherwise, we wouldn’t have to write it in the first place.

Peer Reviews

Peer reviews also improve our code. Reviewers can provide suggestions for improvements.

It also lets us see other people’s styles and learn what we missed from there code.

In the end, reviews help us write clear code at least because we know someone else will read it.

Source control systems are also essential. Not only it helps us undo bad changes easily.

It also lets people look at our code when we check them in.

Conclusion

We should stick with some naming conventions. Like camelCase for variables and upper case for constants.

Writing docs is also important since we need to tell me how to use our stuff.

Peer reviews are also good since we can learn from other people.